/*
 * Copyright (C) 2012  Romain DUBOIS
 * 
 * This file is part of NeMoS - Network and Modular Software
 * 
 * NeMoS is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * NeMoS is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NeMoS.  If not, see <http://www.gnu.org/licenses/>.
 */
package nemos.resources;

import java.io.File;
import java.util.Locale;

/**
 * IResourcesManager : The resources manager interface.
 * 
 * <p>
 * A service implementing this interface provides access to resources:
 * <ul>
 * <li>The user locale and resources</li>
 * <li>External files (input files and persisting files)</li>
 * <li>Localized resources (images, messages, etc.)</li>
 * </ul>
 * </p>
 * 
 * @author Romain DUBOIS
 */
public interface IResourcesManager {

    /**
     * Get the user locale (= User Interface locale).
     * 
     * @return The user locale
     * 
     * @see #setUserLocale(Locale)
     */
    Locale getUserLocale();

    /**
     * Change the user locale.
     * 
     * <p>
     * The user locale can differs from the default one as they have different
     * meanings:
     * <ul>
     * <li>The default locale is mainly used for log entries, it should be
     * defined by the administrator/deployer in the configuration file,</li>
     * <li>The user locale is used by the user interface, it can be changed by
     * the user at any time.</li>
     * </ul>
     * The user locale respects the following rules:
     * <ul>
     * <li>The user locale is persisted. The implementation bundle is free to
     * choose the way to persist the locale, but it is more likely to be through
     * the OSGi Preferences API (Chapter 106), or at least in the OSGi cache,</li>
     * <li>The user locale is associated to the system user,</li>
     * <li>The user locale can be reset to the current default locale by passing
     * {@code null} to this method.</li>
     * </ul>
     * There is no guarantee that the whole User Interface will update to the
     * new user locale. A re-start can be necessary. However, UIs can register
     * {@link IResourcesListener}s in order to be notified of locale changes.
     * </p>
     * 
     * @param pLocale
     *            The new user locale
     */
    void setUserLocale(Locale pLocale);

    /**
     * Get the user resources.
     * 
     * <p>
     * This resources name should be used for each acces to a resource designed
     * for the user.
     * </p>
     * 
     * @return The user resources
     */
    String getUserResources();

    /**
     * Change the user resources.
     * 
     * @param pBaseName
     *            The user resources
     * 
     * @see #getUserResources()
     */
    void setUserResources(String pBaseName);

    /**
     * Get a file object representing an external data file. It is an 'external'
     * file because it should be persisted even if OSGi cache is cleared. Those
     * 'external' files should be used for export, import or save operations.
     * 
     * <p>
     * Depending on the implementation, each type can define a specific folder
     * and a file extension. Do not rely on a specific file name as the
     * implementation is charge of the (type, name) <-> (filename) mapping.
     * </p>
     * 
     * <p>
     * Be aware that :
     * <ul>
     * <li>The file can be acquired for reading or writing purpose,</li>
     * <li>The file may not exist,</li>
     * <li>The file folder (=parent file) exists.</li>
     * </p>
     * 
     * @param pType
     *            The file type
     * @param pName
     *            The file name
     * @return The file in the persistent folders.
     */
    File getExternalFile(String pType, String pName);

    /**
     * Get a resources node for the default locale.
     * 
     * @param pBaseName
     *            The resources base name
     * @param pType
     *            The resources type
     * @return The resources node, or <code>null</code> if it does not exist.
     * @throws UnsupportedResourceType
     *             If the given <code>pType</code> is not handled.
     */
    <T> IResources<T> getResources(String pBaseName, Class<T> pType) throws UnsupportedResourceType;

    /**
     * Get a resources node for the specified locale.
     * 
     * @param pBaseName
     *            The resources base name
     * @param pType
     *            The resources type
     * @param pLocale
     *            The locale for which the resources node is desired
     * @return The resources node, or <code>null</code> if it does not exist.
     * @throws UnsupportedResourceType
     *             If the given <code>pType</code> is not handled.
     */
    <T> IResources<T> getResources(String pBaseName, Class<T> pType, Locale pLocale)
            throws UnsupportedResourceType;
}
